{ "openapi": "3.0.0", "info": { "title": "Master Data API - v2", "description": ">ℹ️ Master Data v2 is not compatible with data entities from previous versions, such as CL and AD.\r\n\r\n[Master Data](https://developers.vtex.com/docs/guides/master-data-introduction) is a secure, fast, scalable, and extensible solution that allows users to create their own entities, store data, and retrieve information directly from the storefront or external integrations.\r\n\r\nSeveral internal VTEX modules use Master Data as a data repository, including Orders and Sales App. \r\n\r\nThere are two main ways to use Master Data:\r\n\r\n- [Directly from the storefront](#directly-from-the-storefront)\r\n- [With an external integration](#external-integrations)\r\n\r\n## Directly from the storefront\r\n\r\nWhen using Master Data within the storefront, consider the following:\r\n\r\n- Use the storefront host to query or store information to avoid issues related to Cross-origin resource sharing (CORS).\r\n- Use the relative path to avoid CORS issues.\r\n- Configure the JSON Schema of the Data Entity to specify which information should be public and which should not be.\r\n- Avoid creating query loops to prevent potential throttling issues or APIs being disabled due to security protection measures.\r\n- Never add authentication keys, such as `X-VTEX-API-AppKey` or `X-VTEX-API-AppToken`, via JavaScript as this could pose security risks.\r\n\r\n## External integrations\r\n\r\nWhen using Master Data to store data from an external integration, such as client data from another service, consider the following:\r\n\r\n- Use the host `{{accountName}}.vtexcommercestable.com.br`.\r\n- Use the authentication keys (`X-VTEX-API-AppKey` ou `X-VTEX-API-AppToken`).\r\n\r\n## Common parameters\r\n\r\n| Name | Description |\r\n| -------- | -------- |\r\n| `accountName` | Account name in VTEX License Manager. |\r\n| `name` | Data Entity name. |\r\n| `schema` | JSON Schema of a Data Entity. |\r\n| `id` | Identifier of a document. |\r\n| `X-VTEX-API-AppKey` | appKey. |\r\n| `X-VTEX-API-AppToken` | appToken. | \r\n\r\n## Index\r\n\r\n### Documents\r\n\r\n- `POST` [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents)\r\n- `PATCH` [Create partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents)\r\n- `GET` [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PUT` [Create document with custom ID or Update entire document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PATCH` [Update partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `DELETE` [Delete document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/documents/-id-)\r\n\r\n### Search\r\n\r\n- `GET` [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search)\r\n\r\n### Scroll\r\n\r\n- `GET` [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll)\r\n\r\n### Schemas\r\n\r\n- `GET` [Get schemas](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas)\r\n- `GET` [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `PUT` [Save schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `DELETE` [Delete schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n\r\n### Indices\r\n\r\n- `GET` [Get indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices)\r\n- `PUT` [Put indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices)\r\n- `GET` [Get index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n- `DELETE` [Delete index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n\r\n### Clusters\r\n\r\n- `POST` [Validate document by clusters](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents/-id-/clusters)\r\n\r\n### Versions\r\n\r\n- `GET` [List versions](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions)\r\n- `GET` [Get version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)\r\n- `PUT` [Put version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/dataentities/{dataEntityName}/documents": { "post": { "tags": [ "Documents" ], "summary": "Create new document", "description": "Creates a new document with an ID automatically generated by VTEX, corresponding to a new or existing data entity. If an unexisting `dataEntityName` is informed in the path, this endpoint will create the data entity as well as the new document. For example, you can create a new customer profile or address.\r\n\r\n>ℹ️ You can use this request to create documents for any data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. However you should be aware of the fields allowed or required for each document you wish to create.\r\n\r\n> To create a document with a custom ID, refer to the [Create document with custom ID](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-) endpoint.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Createnewdocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "email": "clark.kent@examplemail.com", "firstName": "Clark", "lastName": "Kent", "phone": "+12025550195", "documentType": "CPF", "document": "12345678900", "isCorporate": false, "isNewsletterOptIn": false, "localeDefault": "en-US" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentResponse" }, "example": { "Id": "Newsletter-cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "Href": "http://cosmetics2.vtexcommercestable.com.br/api/dataentities/Newsletter/documents/cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "DocumentId": "cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827" } } } } }, "deprecated": false }, "patch": { "tags": [ "Documents" ], "summary": "Create partial document", "description": "This request allows you to partially update a document corresponding to a given data entity.\r\n\r\n>ℹ️ You can use this request to create documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Createorupdatepartialdocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "description": "JSON with the fields to be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "phone": "+12025550195", "isNewsletterOptIn": false } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}": { "get": { "tags": [ "Documents" ], "summary": "Get document", "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getdocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/_fields" }, { "$ref": "#/components/parameters/_schema" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Using_fields_all" }, "example": { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "apiexamples", "dataEntityId": "Newsletter" } } } } }, "deprecated": false }, "put": { "tags": [ "Documents" ], "summary": "Create document with custom ID or update entire document", "description": "Creates a new document with a custom ID, or updates an entire document if there is already a document with the informed ID. For example, you can update a customer profile or address.\r\n\r\n>ℹ️ You can use this request to create or update documents in any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\nA## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Updateentiredocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/_where" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Accept" }, { "name": "id", "in": "path", "description": "ID of the document. If you inform an **unused ID**, this endpoint will create a new document with the informed custom ID, differently from the [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents) endpoint, which automatically generates the ID. If you inform an **existing ID**, this endpoint will update the entire document associated with the informed ID.", "required": true, "style": "simple", "schema": { "type": "string", "example": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "email": "clark.kent@examplemail.com", "firstName": "Clark", "lastName": "Kent", "phone": "+12025550195", "documentType": "CPF", "document": "12345678900", "isCorporate": false, "isNewsletterOptIn": false, "localeDefault": "en-US" } } }, "required": true }, "responses": { "200": { "description": "OK. Document changed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } }, "201": { "description": "Created. Document created successfully." }, "304": { "description": "Not Modified. There were no changes to the document." }, "400": { "description": "Bad Request. Invalid information in JSON." }, "403": { "description": "Forbidden. Unauthorized access." } }, "deprecated": false }, "patch": { "tags": [ "Documents" ], "summary": "Update partial document", "description": "This request allows you to partially update a document corresponding to a given data entity. For example, you can update some fields of a customer profile or address.\r\n\r\n>ℹ️ You can use this request to update documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Updatepartialdocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/_where" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "phone": "+12025550195", "isNewsletterOptIn": false } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false }, "delete": { "tags": [ "Documents" ], "summary": "Delete document", "description": "Deletes a document. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Deletedocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "headers": {} } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/search": { "get": { "tags": [ "Search" ], "summary": "Search documents", "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Searchdocuments", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/REST-Range" }, { "$ref": "#/components/parameters/_fields" }, { "$ref": "#/components/parameters/_where" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/_sort" } ], "responses": { "200": { "description": "OK", "headers": { "REST-Content-Range": { "schema": { "type": "string", "description": "Indicates the range of documents returned in the current response, as well as the total number of documents available in the dataset. The value follows the format `resources={x}-{y}/{total}`, where:\n* `x`: Index of the first document in the returned array.\n* `y`: Index of the last document in the returned array + 1.\n* `total`: Total number of documents that match the query.\nFor example, `resources=0-10/98` indicates that documents from 0 to 9 are returned out of a total of 98 matching documents.", "example": "resources=0-10/98" } } }, "content": { "application/json": { "schema": { "type": "array", "description": "List of documents that correspond to the result of the search.", "items": { "$ref": "#/components/schemas/Using_fields_all" } }, "example": [ { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "apiexamples", "dataEntityId": "Newsletter" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Field 'X' not found in schema" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Cannot filter by private fields" } } } }, "503": { "description": "Service Unavailable. Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`." } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/scroll": { "get": { "tags": [ "Scroll" ], "summary": "Scroll documents", "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Scrolldocuments", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/_token" }, { "$ref": "#/components/parameters/_size" }, { "$ref": "#/components/parameters/_fields" }, { "$ref": "#/components/parameters/_where" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/_sort" } ], "responses": { "200": { "description": "OK", "headers": { "X-VTEX-MD-TOKEN": { "schema": { "type": "string", "description": "Scroll token, which must be informed in the `_token` query parameter in the subsequent requests. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer." } }, "REST-Content-Total": { "schema": { "type": "string", "description": "Total amount of documents corresponding to the query." } } }, "content": { "application/json": { "schema": { "type": "array", "description": "List of documents that correspond to the result of the scroll.", "items": { "$ref": "#/components/schemas/Using_fields_all" } }, "example": [ { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "apiexamples", "dataEntityId": "Newsletter" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Operation not found for this token: 'X'" } } } }, "429": { "description": "Too Many Requests. Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`." } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/schemas": { "get": { "tags": [ "Schemas" ], "summary": "Get schemas", "description": "Retrieves all existing [schemas](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getschemas", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with existing schemas. In case there is only one existing schema, it will be an object instead, without the `name` property and the named `schema` object, following the same structure as the [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-?endpoint=get-/api/dataentities/-dataEntityName-/schemas/-schemaName-) endpoint response.", "items": { "$ref": "#/components/schemas/GetSchemasResponse" } }, "example": [ { "name": "testschema", "schema": { "properties": { "name": { "type": "string" } } } } ] } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/schemas/{schemaName}": { "get": { "tags": [ "Schemas" ], "summary": "Get schema by name", "description": "Returns an existing [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getschemabyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/schemaName" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveschemabynameRequest" }, "example": { "properties": { "name": { "type": "string" } } } } } } }, "deprecated": false }, "put": { "tags": [ "Schemas" ], "summary": "Save schema by name", "description": "Creates or edits a data entity schema. Learn more about [Master Data schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).\r\n\r\n> Note that if you send a `schemaName` that does not exist for that data entity, this request will create it.\r\n\r\nThis request can also be used to [create or edit Master Data v2 triggers](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2).\r\n\r\n> Each Master Data v2 data entity can have up to 60 schemas. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Saveschemabyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/schemaName" } ], "requestBody": { "description": "Request body for saving schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveschemabynameRequest" }, "example": { "properties": { "name": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Success message." } } }, "example": { "Message": "JSON Schema persisted successfully. Revalidation and indexing process running in background." } } } } }, "deprecated": false }, "delete": { "tags": [ "Schemas" ], "summary": "Delete schema by name", "description": "Deletes an existing [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Deleteschemabyname", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/schemaName" } ], "responses": { "204": { "description": "No Content" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/indices": { "get": { "tags": [ "Indices" ], "summary": "Get indices", "description": "Returns the list of [indices](https://developers.vtex.com/docs/guides/master-data-components#index) by data entity. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Index | **View index details** |\r\n| Dynamic Storage | Index | **List index** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getindices", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with information about indices.", "items": { "$ref": "#/components/schemas/Index" } }, "example": [ { "name": "fullName", "acronym": "Newsletter", "isGlobal": false, "multiple": false, "fields": "firstName,lastName" } ] } } } }, "deprecated": false }, "put": { "tags": [ "Indices" ], "summary": "Create index", "description": "Creates an [index](https://developers.vtex.com/docs/guides/master-data-components#index). \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Index | **Edit index** |\r\n| Dynamic Storage | Index | **Create index** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Putindices", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" } ], "requestBody": { "description": "Request body for creating an index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutindicesRequest" }, "example": { "name": "indexName", "multiple": false, "fields": "fieldName" } } }, "required": true }, "responses": { "200": { "description": "OK" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/indices/{index_name}": { "get": { "tags": [ "Indices" ], "summary": "Get index by name", "description": "Retrieves an [index](https://developers.vtex.com/docs/guides/master-data-components#index). \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Index | **View index details** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getindexbyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/index_name" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Index" }, "example": { "name": "fullName", "acronym": "Newsletter", "isGlobal": false, "multiple": false, "fields": "firstName,lastName" } } } } }, "deprecated": false }, "delete": { "tags": [ "Indices" ], "summary": "Delete index by name", "description": "Deletes an [index](https://developers.vtex.com/docs/guides/master-data-components#index). \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Index | **Remove index** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Deleteindexbyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/index_name" } ], "responses": { "204": { "description": "No Content" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}/clusters": { "post": { "tags": [ "Clusters" ], "summary": "Validate document by clusters", "description": "Checks if a document is present in one or more clusters (specific set of field values).\r\n\r\n>ℹ️ There is a limit of five rules per request. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Validatedocumentbyclusters", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "description": "Request body for validating a document by clusters", "content": { "application/json": { "schema": { "type": "array", "description": "List of cluster validation rule information.", "items": { "type": "object", "description": "Cluster validation rule information.", "properties": { "name": { "type": "string", "description": "Cluster name.", "example": "male" }, "rule": { "type": "string", "description": "Cluster validation rule.", "example": "gender=male" } } } }, "example": [ { "name": "male", "rule": "gender=male" }, { "name": "complex", "rule": "((gender=male AND percent=0.35) AND any is null) AND (name=*go*)" }, { "name": "complex2", "rule": "((gender=male AND percent=0.35) AND any is not null) OR (name=*go*)" }, { "name": "createdIn", "rule": "createdIn between 2015-10-28 AND 2015-10-30" } ] } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with objects validating each cluster rule.", "items": { "type": "object", "description": "Cluster rule validation object.", "properties": { "name": { "type": "string", "description": "Cluster name." }, "isValid": { "type": "boolean", "description": "Informs if the document is valid according to the cluster rule (`true`) or not (`false`)." } } } }, "example": [ { "name": "male", "isValid": false }, { "name": "complex", "isValid": false }, { "name": "complex2", "isValid": false }, { "name": "createdIn", "isValid": false } ] } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}/versions": { "get": { "tags": [ "Versions" ], "summary": "List versions", "description": "Lists the versions of a document. \r\n\r\n>ℹ Master Data documents are versioned. This means that, for each change, a new version is generated. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Listversions", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "name": "load", "in": "query", "description": "If true, return all the fields in each version of the document.", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "fields", "in": "query", "description": "If `load` is true, the response will return only these specific fields.", "required": false, "schema": { "type": "string", "default": "id,dataEntityId,isNewsletterOptIn,createdBy" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Listversion" } }, "example": [ { "id": "_EAR0cJ7XB5k5grnmm0zeKGlVvVM9WCPy_", "date": "2016-10-18T16:53:32+00:00", "document": { "id": "72e7f8dd-1168-23ec-82ac-0e2b61663eb4", "dataEntityId": "Newsletter", "isNewsletterOptIn": true, "createdBy": "81fc8b10-25b7-48de-b425-7b93554002cc" } }, { "id": "_E5SH9WXVvhPBNnbQtYAAGqrIysIeNYhV_", "date": "2016-09-08T20:11:42+00:00", "document": { "id": "72e7f8dd-1168-23ec-82ac-0e2b61663eb4", "dataEntityId": "Newsletter", "isNewsletterOptIn": true, "createdBy": "81fc8b10-25b7-48de-b425-7b93554002cc" } } ] } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}/versions/{versionId}": { "get": { "tags": [ "Versions" ], "summary": "Get version", "description": "Returns the version of a document. \r\n\r\n>ℹ Master Data documents are versioned. This means that, for each change, a new version is generated. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getversion", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/versionId" } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Getversion" }, "example": { "id": "cSIAceEelBEmSOqRkzJYLRQuGgi6.CqF", "author": "1f936e42-79b3-4e5b-91d2-da9a8af0b215", "document": { "id": "cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "dataEntityId": "Newsletter", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "followers": [], "schemas": [ "testprofile", "testprofile2" ], "email": "clark.kent@examplemail.com" } } } } } }, "deprecated": false }, "put": { "tags": [ "Versions" ], "summary": "Update version", "description": "Updates the document's version value.\r\n\r\n>ℹ Master Data documents are versioned. This means that, for each change, a new version is generated. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Putversion", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "name": "versionId", "in": "path", "description": "ID of the version to update", "required": true, "style": "simple", "schema": { "type": "string", "example": "_8sZcvyj4nng7FgA2RgtVVZmkIxb4Pbfe_" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } }, "304": { "description": "Not Modified" } }, "deprecated": false } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "components": { "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } }, "schemas": { "DocumentRequest": { "title": "DocumentRequest", "type": "object", "description": "This can be any pure JSON document. Add new _Key-Value_ pairs to test.", "additionalProperties": true }, "Using_fields_all": { "title": "Using_fields=_all", "required": [ "id", "accountId", "accountName", "dataEntityId" ], "type": "object", "description": "Document information.", "properties": { "id": { "type": "string", "description": "ID of the document." }, "accountId": { "type": "string", "description": "ID of the VTEX account." }, "accountName": { "type": "string", "description": "Name of the VTEX account." }, "dataEntityId": { "type": "string", "description": "Data entity name." } } }, "SaveschemabynameRequest": { "title": "SaveschemabynameRequest", "required": [ "properties" ], "type": "object", "description": "Schema.", "properties": { "properties": { "$ref": "#/components/schemas/Properties" } } }, "GetSchemasResponse": { "title": "GetSchemasResponse", "required": [ "name", "schema" ], "type": "object", "description": "Schema.", "properties": { "name": { "type": "string", "description": "Schema name." }, "schema": { "type": "object", "description": "Object with schema properties.", "properties": { "properties": { "$ref": "#/components/schemas/Properties" } } } } }, "Properties": { "title": "Properties", "required": [ "name" ], "type": "object", "description": "Object containing schema properties.", "properties": { "name": { "$ref": "#/components/schemas/Name" } } }, "Name": { "title": "Name", "required": [ "type" ], "type": "object", "description": "Property name.", "properties": { "type": { "type": "string", "description": "Type of property.", "enum": [ "array", "boolean", "integer", "number", "object", "string" ], "example": "string" } } }, "PutindicesRequest": { "title": "PutindicesRequest", "required": [ "name", "multiple", "fields" ], "type": "object", "description": "Request body object.", "properties": { "name": { "description": "Name to identify the index.", "type": "string", "example": "indexName" }, "multiple": { "description": "Determines whether the values need to be unique. If false, values must be unique.", "type": "boolean", "example": false }, "fields": { "description": "Comma-separated fields of the index.", "type": "string", "example": "fieldName" } } }, "Index": { "type": "object", "description": "Index information.", "properties": { "name": { "type": "string", "description": "Index name." }, "acronym": { "type": "string", "description": "Data entity name." }, "isGlobal": { "type": "boolean", "description": "Defines whether the index is global (`true`) or not (`false`).", "deprecated": true }, "multiple": { "type": "boolean", "description": "Determines whether the values need to be unique. If `false`, values must be unique." }, "fields": { "type": "string", "description": "Comma-separated fields of the index." } } }, "Listversion": { "title": "Listversion", "required": [ "id", "date" ], "type": "object", "description": "Version information.", "properties": { "id": { "type": "string", "description": "Version ID." }, "date": { "type": "string", "description": "Date when the version was created in ISO 8601 format." }, "document": { "type": "object", "description": "Information about the document.", "properties": { "id": { "type": "string", "description": "Document ID." }, "dataEntityId": { "type": "string", "description": "Data entity name." }, "isNewsletterOptIn": { "type": "boolean", "description": "Indicates whether client otped to receive the store newsletter (`true`) or not (`false`).", "nullable": true }, "createdBy": { "type": "string", "description": "ID of the user who created the document." } } } } }, "Getversion": { "title": "Getversion", "required": [ "id", "author", "document" ], "type": "object", "description": "Request body object.", "properties": { "id": { "type": "string", "description": "Version ID." }, "author": { "type": "string", "description": "ID of the user who created the version." }, "document": { "$ref": "#/components/schemas/Document" } } }, "Document": { "title": "Document", "required": [ "id", "dataEntityId", "accountId", "accountName", "followers" ], "type": "object", "description": "Document information.", "properties": { "id": { "type": "string", "description": "ID of the document." }, "dataEntityId": { "type": "string", "description": "Data entity name." }, "accountId": { "type": "string", "description": "ID of the VTEX account." }, "accountName": { "type": "string", "description": "Name of the VTEX account." }, "followers": { "type": "array", "description": "Followers.", "deprecated": true, "items": { "type": "string", "description": "Follower." } }, "schemas": { "type": "array", "description": "Schemas which the document is compliant with.", "items": { "type": "string", "description": "Schema name." } }, "email": { "type": "string", "description": "User email." } } }, "CreateDocumentResponse": { "required": [ "Id", "Href", "DocumentId" ], "type": "object", "description": "Response body object.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created, with data entity prefix." }, "Href": { "type": "string", "description": "Document reference URL." }, "DocumentId": { "type": "string", "description": "ID of the document that was created." } } }, "documentResponse": { "required": [ "Id", "Href" ], "type": "object", "description": "Response body object.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created or updated." }, "Href": { "type": "string", "description": "Document reference URL." } } } }, "parameters": { "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "dataEntityName": { "name": "dataEntityName", "in": "path", "required": true, "description": "Name of the data entity.", "schema": { "type": "string", "example": "Newsletter" } }, "_schema": { "name": "_schema", "in": "query", "description": "Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters.", "required": false, "style": "form", "schema": { "type": "string", "example": "schema" } }, "id": { "name": "id", "in": "path", "description": "ID of the Document.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b818cbda-e489-11e6-94f4-0ac138d2d42e" } }, "versionId": { "name": "versionId", "in": "path", "description": "ID of the version to update.", "required": true, "style": "simple", "schema": { "type": "string", "example": "_8sZcvyj4nng7FgA2RgtVVZmkIxb4Pbfe_" } }, "_where": { "name": "_where", "in": "query", "description": "Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`).", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName is not null" } }, "index_name": { "name": "index_name", "in": "path", "description": "Name of the index.", "required": true, "style": "simple", "schema": { "type": "string", "example": "{{index_name}}" } }, "schemaName": { "name": "schemaName", "in": "path", "description": "Name of the schema.", "required": true, "style": "simple", "schema": { "type": "string", "example": "{{schema}}" } }, "REST-Range": { "name": "REST-Range", "in": "header", "description": "Specifies the range of documents to be returned in the response. The value should follow the format `resources={x}-{y}`, where:\n* `x`: Index of the first document in the returned array.\n* `y`: Index of the last document in the returned array + 1.\n\nThis field controls pagination by defining the subset of documents to be retrieved. The maximum number of documents returned per query is limited to 100.\nFor example, `resources=0-10` returns the first 10 documents.", "required": true, "style": "simple", "schema": { "type": "string", "example": "resources=0-10" } }, "_fields": { "name": "_fields", "in": "query", "description": "Fields that should be returned by document. Separate fields' names with commas. For example `_fields=email,firstName,document`. You can also use `_fields=_all` to fetch all fields.", "required": false, "style": "form", "schema": { "type": "string", "example": "email,firstName,document" } }, "_sort": { "name": "_sort", "in": "query", "description": "Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order.", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName ASC" } }, "_token": { "name": "_token", "in": "query", "description": "Value of the `X-VTEX-MD-TOKEN` token obtained in the response header of the first request, necessary on subsequent requests to continue scrolling through documents. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.", "required": false, "style": "form", "schema": { "type": "string", "example": "123456" } }, "_size": { "name": "_size", "in": "query", "description": "Inform the number of documents per request. Maximum value of `1000`.", "required": false, "style": "form", "schema": { "type": "integer", "default": 100 } } } }, "tags": [ { "name": "Documents" }, { "name": "Search" }, { "name": "Scroll" }, { "name": "Schemas" }, { "name": "Indices" }, { "name": "Clusters" }, { "name": "Versions" } ] }